This tutorial will explain the basics of writing a Windows DLL. I will direct it at Visual Basic programmers who have decided they need to write a DLL for their VB applications. However, VB programmers not are the only users of DLLs. Those programmers who want to write a DLL to interface with other languages will also find this tutorial useful.
In addition this tutorial is specific to writing a DLL using C.
What is a Dynamic Link Library?
A Dynamic Link Library, DLL, is a library of functions callable by an application at runtime. The application and functions within the DLL are not bound until the application program is executed.
Normally the functions in a DLL are for a particular purpose (internet access, graphing, serial port communication). They may also be a collection of functions required by an application and only be specific to that application. This is only convention, if you are writing a DLL you can put whatever functions you want into it.
If you are going to write and distribute a DLL, you do not need to register its name nor get an ID from anyone. You can name it whatever you want, but please try to make it unique. If you call your DLL "KERNEL.DLL" you will have problems with it (KERNEL is a Microsoft Windows DLL used to perform operating system kernel functions).
An application can bind to a DLL in two ways:
Load Time Binding
On Call Binding
Load Time Binding loads the DLL when an application that uses it is loaded for execution. Windows loads the DLL for the application.
With On Call Binding, the DLL is loaded when it is needed. If it is never needed by the application it will never be loaded.
Visual Basic loads DLLs when the form that contains their Declare statement is loaded. If a VB application places the DLL function declare in a module or on a form that is loaded when the application is loaded, then the DLL will be bound at application load time. If the declare is placed in a form that is dynamically loaded by the VB application, then the DLL will be loaded when the form is loaded.
One last note on loading DLL's, Windows will locate a DLL in the following order:
In memory, a DLL, once loaded, is global to all of Windows until it is unloaded.
In the directory where the application was loaded from
In the windows directory
In the windows\system directory
In directories specified in the DOS PATH
What do I need to write a DLL?
As of today, most DLL's are written in C. It is possible to write a DLL in PASCAL/Delphi or assembly language. (There was a product on the market that allowed DLL's to be written in Basic but I have not seen mention of it for while. If anyone knows of this, please let me know.)
In order to write a DLL you will need a compiler capable of creating Windows DLL. The four most popular C compilers that can do this are:
Microsoft Visual C++
Borland C++ for Windows
Symantec C++ for Windows
Watcom C++
If you do not have a compiler, you will need one to write a DLLs.
In addition to the compiler, you will need knowledge of C and the Windows API.
NOTE: C is the language that is used to write a DLL, not C++. C++ is an object oriented extension of C. If you have a C++ compiler, it can handle C just fine. You can also write non-exported functions as C++ objects, but the functions that are called into from Windows applications must be C functions, not C++ functions or methods.
DLL Requirements
A Windows DLL requires only one function called LibMain. If a DLL does not have a LibMain it will not work.
Windows calls the LibMain function of a DLL to initialize the DLL. For most simple DLL's, you code LibMain as follows:
int FAR PASCAL _export LibMain(HANDLE hInstance,WORD wDataSeg,
WORD wHeapSize,LPSTR lpszCmdLine)
{
if(wHeapSize > 0)
UnlockData(0);
return(1);
}
You can find details of LibMain in the Windows API documentation.
The only other requirement of functions in a DLL is that those functions that can be called from outside the DLL, must be declared "FAR PASCAL _export". If you do not declare them this way, you will not be able to call them.
You will also need a special DEF file for a DLL. Below is a sample that was generated by Microsoft Visual C++. Most of today's compilers will generate the DEF for you, but if yours does not, create one that looks like this:
LIBRARY <your DLL name goes here>
EXETYPE WINDOWS
CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD MOVEABLE SINGLE
HEAPSIZE 1024
EXPORTS
WEP PRIVATE
; To implement your own Windows Exit Procedure add the following
; function to your application (referring to it in the .def file is
; not required.) The extern "C" is only required if module is C++.
; extern "C" int FAR PASCAL _WEP(int)
; {
; /* Your WEP functionality goes here */
; return 1;
; }
That is it. After you compile and link, you can begin testing your DLL.
The samples that go with this tutorial contain all of this basic information. You can use it as a template to start writing your first DLL.
What can I do in a DLL?
Many people ask what is permissible in a DLL. Well, just about anything is permissible. When an application calls a DLL function, the DLL is executing as an extension of the application's task. Any files it opens are open to the task; any memory allocated is allocated from the task's local or global heaps. Just keep this in mind and you will be fine.
Let's look at a small example. If you write a DLL that executes a LocalAlloc API call for 32000 bytes and it does not call a LocalFree on that memory handle before returning, the DLL will have just taken 32000 bytes of the applications local heap. You will probably start getting out of memory messages from the application.
Some of the things you might want to do in a DLL are:
Make GDI function calls to paint the screen.
Allocate Windows global memory
Perform file I/O
Search Windows internal tables
Perform port I/O
Call other API's
All of these things are possible, the most important thing to remember is to write your DLL as clean as possible. If you allocate a resource, and you do not need to keep it, free it before you return from your DLL function. Always remember, a DLL can cause all kinds of problems in Windows and they might not show until your DLL has long been unloaded.
Also remember that a DLL is global. If you store data in a global variable inside a DLL and two tasks are currently using the DLL, they will both be accessing the same global area in the DLL. In addition, when Windows unloads the DLL, you lose the global data.
BE CAREFUL AND KEEP IT CLEAN.
Where can I get sample DLL source?
You can find source code for DLL's on almost any Internet FTP site dealing with Windows programming as well as other on-line service forums. The problem with most of this source is that the DLL was written for a purpose. You have to wade through hundreds of lines of code just to get an idea of what you need for a simple DLL.
Included with this tutorial is a sample DLL that does nothing but add two arguments and return the result. It contains the source code and project files for both Borland C++ and Microsoft Visual C++. In addition it contains a VB program, with source, that calls the DLL.
If there is a demand for more complicated DLL's (maybe some showing how to perform GDI calls or access VBX control information) I could probably be persuaded to add more samples to this tutorial. Let me know.
Where can I get more information on writing a DLL?
Most good books on C programming for Windows will include a chapter or two on writing a DLL. Browse your local book store and find one you like.
Since writing a DLL is really just writing a Windows program, you will need access to the Windows API documentation. You will also want to get information on writing programs using GDI, KERNEL and other part of Windows.
About the author
I, Glenn Jones, have been a professional programmer for 16 years. For most of this time I have been designing, writing and supporting system software (compilers, debuggers, code generators, communication API's ect). I have worked in a variety of environments and with many different languages and compilers. At this point I am dedicated to describing and helping programmers with the debugging process. I believe that the first step in debugging a program is understanding the principles of the environment for which you are writing. If you need to write and debug a DLL, then you need to know how to write a DLL correctly.
If you have any questions or comments about this tutorial or suggestions for future tutorials, please contact me at gdjones@ix.netcom.com.
Have fun.
Copyright and Distribution
This document is Copyright ( 1995 by Glenn D. Jones. It may be distributed freely for non-commercial use. It may not be included in print or electronically published for sale without the permission of the author.
Microsoft Visual C++, Microsoft Visual Basican Windows are copyright Microsoft Corporation.
Borland C++ is copyright Borland International, Inc.
